home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Night Owl 6
/
Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso
/
027a
/
clhlp110.zip
/
CLIPHELP.DOC
< prev
next >
Wrap
Text File
|
1991-10-24
|
38KB
|
1,004 lines
HHHHHHH.
HH:^^^^^ HH. HH. (C) 1991 S.R. Eddy & Associates
HH: HH: ^^
HH: HH: HH. HHHHHHH. HH. HH.
HH: HH: HH: HH:^^HH: HH: HH: HH.
HH: HH: HH: HH: HH: HH: HH: HH:
HH: HH: HH: HH: HH: HHHHHHHH: HHHHHHH. HH: HHHHHHH.
HHHHHHH. HH: HH: HHHHHHH: HH:^^^HH: HH:^^HH: HH: HH:^^HH:
^^^^^^^ ^^ ^^ HH:^^^^^ HH: HH: HHHHHHH: HH: HH: HH:
HH: HH: HH: HH:^^^^^ HH: HH: HH:
^^ HH: HH: HHHHHHH. HH: HHHHHHH:
^^ ^^ ^^^^^^^ ^^ HH:^^^^^
Perth, Western Australia HH:
^^
An easy way to add
F U L L C O L O R C O N T E X T - S E N S I T I V E H E L P
to your Clipper (Summer '87 and 5.01) applications
Version 1.1
October 24, 1991
S.R. Eddy & Associates
267 Acourt Road
CANNING VALE 6155
Western Australia
Tel: (09) 455-1004
CONTENTS
Disclaimer ....................................... 3
License .......................................... 3
Registration ..................................... 3
Order Form ....................................... 5
1. Purpose ..................................... 6
2. Installation ................................ 6
3. ClipHelp demonstration ...................... 6
4. Steps involved in creating and incorporating
Help in your application ............... 7
5. Preparing Help Text ......................... 7
6. Creating the on-screen file which your
application will use ................... 8
7. Adding color to your on-screen help file .... 8
8. Rewriting HELP.TXT with the codes entered in
the color editor ....................... 10
9. Adding context-sensitivity to your HELP.TXT
file ................................... 11
10. Printing a User Manual (Registered version) . 12
11. Clipper Summer '87 version - PUBLIC variables
to declare in your application ......... 14
12. Clipper 5 version - Declarations in your
application .................................14
13. Points to remember when using INKEY(0) ...... 15
14. Linking ClipHelp's .OBJ and .LIB files in
your application ....................... 15
15. ClipHelp's command line parameters .......... 16
16. Credits ..................................... 17
17. Copyright, Trademark etc .................... 17
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 2 S.R. Eddy & Assoc
DISCLAIMER
S.R. Eddy & Associates hereby disclaims all warranties relating to
this product, whether express or implied, including without
limitation any implied warranties of merchantability or fitness
for a particular purpose. S.R. Eddy & Associates cannot and will
not be liable for any special, incidental, consequential, indirect
or similar damages due to loss of data or any other reason, even
if S.R. Eddy & Associates or an authorized S.R. Eddy & Associates
agent has been advised of the possibility of such damages. In no
event shall the liability for any damages ever exceed the price
paid for the license to use software, regardless of the form
and/or extent of the claim. The user of this program bears all
risk as to the quality and performance of the software.
LICENSE
ClipHelp is a Shareware product and is made available to the
general computing public as such for evaluation. Users are
licensed to operate ClipHelp on their personal computers for the
purpose of test and evaluation on a trial basis for a period of 30
days. If the user decides the program is not of sufficient merit
to warrant purchase through registration with S.R. Eddy &
Associates, the program should be removed from the user's personal
computer. Otherwise, if the program is deemed useful and the user
has used or intends to use it in any of his or her programs,
registration with S.R. Eddy & Associates is required.
Registered users are those users that elect to pay for ClipHelp
and register by payment with S.R. Eddy & Associates. By virtue of
registration and payment for the program, registered users are
granted a license to continue to utilize the program on their
personal computer for as long as they choose. This license
authorizes the user to use the program on any personal computer
system he or she may own so long as the program is operated on
only one computer system at a time.
Site licenses for use of ClipHelp on multiple computers are
available upon request at a reduced fee based upon the number of
single machines licensed for use.
REGISTRATION
ClipHelp is the sole property of S.R. Eddy & Associates. The
Shareware version, and ONLY that version, may be freely copied and
transferred to individual parties for evaluation purposes. The
Shareware version, and ONLY that version, may be posted on
Bulletin Board Systems (BBS) for electronic access as long as NO
FEE is charged for its distribution except for private BBS
operations that charge a regular user subscription fee. Computer
information services are authorized to post this product for
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 3 S.R. Eddy & Assoc
subscriber access. The Shareware version of ClipHelp may NOT be
distributed on diskette by any disk distributor/vendor that
charges more than $12.00 for the diskette upon which the program
and attendant files are recorded without written consent from
S.R.Eddy & Associates.
ClipHelp is a fully functional Shareware product. Shareware is a
computer program distribution/marketing method that permits
potential buyers to thoroughly try the program prior to purchase.
It is NOT free and it is not in the Public Domain. If, after
evaluating the program, you find it to be useful enough to
incorporate into one or more applications, you are expected to pay
for it by registering with S.R. Eddy & Associates. The
registration fee is $48.00 and the registered version which will
be sent in return, which is NOT distributed as Shareware, will not
contain Shareware labels nor the closing message. The registered
version also includes the ability to print a paginated User Manual
with Table of Contents generated from the on-screen help data
which you incorporate in your application.
You may register by completing and despatching the form on the
following page together with the registration fee stated therein.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 4 S.R. Eddy & Assoc
O R D E R F O R M
===================
Mail To: S.R. Eddy & Associates Phone:(Intnl) (+61) 9 455-1004
267 Acourt Road
CANNING VALE, PERTH
WESTERN AUSTRALIA 6155
____________________________________________________________________
Please tick as appropriate:
Mastercard ____ Visa ____ Bankcard ____ (Australia Only)
Cheque ____ (Sorry... Aust $, drawn on Australian Banks only.)
Card Number: _____________________________ Expiry Date: ________
Name: ________________________________________________________
Signature: ________________________________________________________
Company: __________________________________________________________
Position: __________________________________________________________
Address: __________________________________________________________
City: ________________ State: _______________ Zip/Postcode _____
Country: _____________________ Phone: ___________________________
DESCRIPTION QTY UNIT TOTAL
PRICE AMOUNT
____________________________________________________________________
Within Australia:
ClipHelp (program and manual on disk) ____ @ Aust$48.00 _______
(Price includes airmail postage & packing)
Other than Australia:
ClipHelp (program and manual on disk) ____ @ US$48.00 _______
(Price includes airmail postage & packing)
========
TOTAL ORDER VALUE (Aust/US)$ ________
Preference: 5.25" (360k) Disk ____ or 3.5" (720k) Disk ____
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 5 S.R. Eddy & Assoc
1. Purpose
ClipHelp is intended to help you incorporate attractive and
effective on-screen help in your applications, providing:
* An almost unlimited number of help topics.
* Topics size of from just a few lines to a virtually unlimited
length.
* Easily incorporated context-sensitivity.
* Single and multi-user applications suitability.
* Full color potential - almost all of the 128 basic
combinations and their flashing counterparts.
* Easily learned color editing facility.
* Ability to use text generated with your preferred ASCII text
editor, such as QEdit.
* Automatic generation of a User Manual based on the on-screen
help text file, including a table of contents (Registered
users version).
2. Installation
Create a sub-directory for ClipHelp (such as c:\ch) and extract
all files into it.
3. ClipHelp Demonstration
After installation give the command 'cliphelp' from within the
sub-directory into which the ClipHelp files have been extracted
and select the first option of the ClipHelp menu - 'About
ClipHelp'.
This will use ClipHelp's on-screen help facility to present an
illustrated description of itself.
Individual topics may be longer than the screen panel in which
they appear. Use <cursor down> and <cursor up> to scroll through
a topic's text beyond the screen's limits, and <PgDn> or <PgUp> to
summon the next or previous topic to the screen.
<Alt-F1> causes an index of help topics to appear. Using this, it
is possible to jump directly to a required topic.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 6 S.R. Eddy & Assoc
4. Steps involved in creating and incorporating Help in your
Application
a) Create your HELP.TXT file with an ASCII text editor following
the guidelines given in the next section.
b) Run ClipHelp and use its 'Make Help File' option to generate
a HELP.DAT file from your HELP.TXT file.
c) Use ClipHelp's 'Edit Colors' option to add color to HELP.DAT.
d) Use ClipHelp's 'Rewrite Text' option to generate a
replacement HELP.TXT file incorporating color code
information.
[Optionally use the ASCII text editor to revise the color-
coded HELP.TXT file and proceed through b), c) and d) again
as many times as necessary.]
[ e) Optionally set PUBLIC (STATIC in the Clipper 5 version)
variable 'hlp_var' to differing values at points in your
program where you wish your on-screen help to be context-
sensitive then use the ASCII text editor to write the same
values in the appropriate places in your HELP.TXT file (as
explained later) and regenerate HELP.DAT through steps b), c)
and d). ]
f) Copy the HELP.DAT file and the appropriate ClipHelp .OBJ and
.LIB files (as explained later) to your application's sub-
directory, incorporate the lines of code given later in your
application, compile and link.
5. Preparing Help Text
Use an ASCII text editor such as QEdit to prepare your help text,
observing the following rules:
a) The file should have the name HELP.TXT.
b) The maximum width of your help text should be 72, so set your
editor's right margin to that value.
c) Precede topic titles with the characters '#$$' in the first
three columns followed by a space and then the title in up to
35 characters, eg:
#$$ Entering sales slip details
d) Of the extended ASCII values 0 to 255 there are very few that
have to be avoided:
009 (tab) Use spaces instead.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 7 S.R. Eddy & Assoc
219 (solid box) This will not matter if you are
preparing a color help facility as
you can use color to simulate this
character.
e) Do NOT prepare your text file with a word processor which
inserts codes for line wrap, bold, underlining etc.
Remember to take note of the comments later in this document about
editing a HELP.TXT file after color information has been added to
it by ClipHelp's color editor.
6. Creating the on-screen file which your application will use
You must of course have created a HELP.TXT file as described in
the preceding section before proceeding with the following.
At the command prompt enter the command:
cliphelp [[[<ExpC1>] <ExpC2> ] ...]
<ExpC1> etc are optional parameters listed later in this document.
(It is unlikely that you will need to know about these at this
stage but if the program should not run satisfactorily on your
screen see whether there is anything under 'ClipHelp parameters'
which could help you.)
When ClipHelp's opening screen appears press <cursor down> until
the highlight rests on 'Make Help File' then press <Enter>.
The message line towards the bottom of the screen will ask you to
confirm your intentions with the message 'Create HELP.DAT (Y/-)?'.
If you have prepared your HELP.TXT file, tap a 'y' to proceed or
any other character to cancel the command.
The message 'Creating HELP.DAT' will flash in the message line
while the file is being created followed by confirmation that the
file has been created.
During the creation of HELP.DAT information is written at the
beginning of the file about the whereabouts of topic titles and
their associated text.
7. Adding color to your on-screen help file
Select the option 'Edit Colors' from the ClipHelp menu.
The ClipHelp color editor screen will be displayed with the
beginning of your HELP.DAT file in the edit window.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 8 S.R. Eddy & Assoc
At the top of the screen is a color code panel with a rectangle
superimposed on the default help text color code.
The word 'Activity:' appears on the line immediately below the
color code panel. As you use the editor one of the following
descriptions will appear:
Description Meaning
----------- -------
Scrolling The content of HELP.DAT can be scrolled
through the window by pressing <cursor down>
or <cursor up>.
Selecting Appears when <F3> is first pressed accompanied
by flashing of the rectangle on the currently
selected color code. In this mode the
flashing rectangle will move in the direction
of any cursor key pressed, allowing selection
of another color.
Moving Appears when <F3> is pressed while in the
Selecting mode together with a flashing arrow
as a pointer above the first column of the
first line of the edit window. You can then
use <cursor right> or <cursor left> to move
the pointer until it is at the beginning of
the block which you wish to paint with the
color you selected.
Painting Appears when <F6> is pressed while in the
Moving mode. In this mode the right and left
cursor keys behave as follows:
<cursor right> Colors the character position
beneath the flashing arrow with
the selected color and causes
the arrow to advance one
column.
<cursor left> Moves the flashing arrow back a
column but does not affect the
color.
Moving Appears when <F6> is pressed while in Painting
mode. Behaves exactly as described previously
against 'Moving'.
Editing Appears when <F10> is pressed while in
Scrolling mode and allows the text of the line
at the top of the window to be edited. Topic
title lines, however, are not allowed to be
edited because that might affect entries off-
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 9 S.R. Eddy & Assoc
screen at the top of the file which were
entered when HELP.DAT was created. (Topic
titles can be edited later in the HELP.TXT
file which you recreate with ClipHelp's
'Rewrite Text' - see section later in this
document.)
At the bottom of the screen is a list of function keys which are
used to enter and edit color attributes. Function keys which
toggle conditions on and off are indicated in bright red, the
remainder in bright white.
At any given moment only the function keys available for use will
be easily legible; others will be displayed in low intensity to
remind you of their existence but indicate their unavailability at
that time.
The top line of the screen is used to describe what is happening
and the significance of particular keys.
Some function keys offer useful short cuts:
<F4> Automatically selects the default help text color
and repositions the color code selection rectangle
at that code.
<F5> Selects the color attribute of the character
beneath the flashing arrow. (A quick way of color
editing a line which has recently been edited in
HELP.TXT.)
<F8> Repeats the color attributes of the line at the top
of the window in the line beneath it. (A quick way
to do something like color a message panel.)
<F9> Deletes the color attributes of the line at the top
of the window and replaces them with the default
help text attribute. To avoid accidents through
inadvertent use this will only be done if you
answer the confirmatory question which follows with
a 'y'.
Press <F2> to save your selections when you have finished editing
the color attributes of a line, or <Esc> to cancel them and revert
to the original attributes.
8. Rewriting HELP.TXT with the codes entered in the color editor
It is most important that this be done following any use of the
'Edit Colors' option during which changes were made, otherwise
such changes will be lost should you need to recreate the HELP.DAT
file to reflect changes in HELP.TXT.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 10 S.R. Eddy & Assoc
Select the 'Rewrite Text' option of the ClipHelp menu. You will
be asked to confirm your intentions with the message 'Rewrite
HELP.TXT from HELP.DAT (Y/-)?'. Tap a 'y' to confirm. Your
HELP.TXT file will be rewritten together with information about
the colors which have been entered in HELP.DAT. If a previous
HELP.TXT is found it will be safely renamed HELP.BAK before
HELP.TXT is rewritten.
When you next look at HELP.TXT in your ASCII text editor you will
notice that on the lines where color has been introduced color
information will appear starting at column 79. Try not to disturb
this information if you need to edit such lines. Make sure it
always starts at column 79. If an accident occurs you will be
able, in most circumstances, to repair the damage when you next
use ClipHelp's 'Edit Colors' option.
In particular, try not to accidentally 'wrap' the color
information with your text! Keeping a backup copy of HELP.TXT is
a good idea.
9. Adding context sensitivity to your HELP.TXT file
When <F1> is pressed in your application ClipHelp searches topic
entries at the top of HELP.DAT to see whether the character string
currently assigned to PUBLIC variable 'hlp_var' (STATIC variable
'hlp_var' in the Clipper 5 version) is there somewhere. If a
match is found ClipHelp displays that topic; if not it displays
the Help Topic Index.
There are (at least) two techniques you can use to introduce
context sensitivity:
Clipper Summer '87 -
a) At appropriate spots in your source code assign PUBLIC
variable 'hlp_var' all - or a unique part of - the applicable
help topic. For example, using the sample help topic given
earlier in this document:
#$$ Entering sales slip details
you might, in the interests of brevity, use the unique part:
hlp_var = 'sales slip'
Please note that case IS important.
b) In lieu of all or part of help topics text use a unique code
such as 'h1v', 'h2v' etc. Be sure to maintain a record of
the codes you have used to avoid double usage. (If you have
Turbo GREP or a similar program you can readily get a list of
such lines from all source code files.) Using this technique
you would put in your source code entries such as:
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 11 S.R. Eddy & Assoc
hlp_var = 'h1v'
then, with your ASCII text editor, put 'h1v' on the
appropriate help topic title line of your HELP.TXT file
starting at column 45, ie
#$$ Entering sales slip details h1v
Clipper 5 -
The technique of referring to a portion of the help topic or
alternatively using unique codes such as 'h1v', 'h2v' etc is the
same as that described above. However, hlp_var is a file-wide
static variable in CLHLP501.OBJ and values are passed to it with
a call to function SetHV(). The equivalents to the examples above
would be:
SetHV( 'sales slip' )
and
SetHV( 'h1v' )
SetHV() returns the current hlp_var value, so that you may save it
on calling a routine requiring a new value and restore it on
return from it, eg:
LOCAL cur_hv := SetHV( 'h21v' )
.
.
SetHV( cur_hv )
10. Printing a User Manual
The 'Print User Man' option translates your HELP.DAT file into a
paginated user manual complete with a table of contents.
When you select this option you will be asked to enter the
following pieces of information to be incorporated in your manual:
Program Title
This is the full title to appear on the first page.
Abbreviated Title
This is the shortened title which will appear at the
bottom left of each page.
Your Business Name
This is your full business name, to appear on the first
page.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 12 S.R. Eddy & Assoc
Abbreviated Name
The shortened business name to appear at the bottom
center of each page.
Your address
Full address - street, city, state, zip.
Your Telephone, Fax & Data Numbers
Self-explanatory.
Printer output should suit most industry-compatible laser and dot
matrix printers. The program endeavors to filter out the ASCII
characters < 32 likely to feature in your help text in case they
interfere with your printer's operation.
You will find that the cover and table of contents will be the
last two pages printed. To avoid taking liberties with your
printer the cover is a very plain affair which you may wish to
replace with something more exciting.
Prior to printing, you may find it beneficial to use one of the
several utilities generally available from bulletin boards which
redirects printer output to a disk file. You can then examine the
print file with your ASCII text editor to ensure that page breaks
are suitable.
Should you find it desirable to force a page break at a place
prior to that selected by the program, note the line or lines,
then edit the HELP.TXT file and place a slash ('/') in column 73
on those lines, being careful not to displace any color codes from
their start column of 79. Next, run ClipHelp's 'Make Help File'
option to remake HELP.DAT from the edited HELP.TXT file and then
re-run the 'Print User Man' option.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 13 S.R. Eddy & Assoc
11. Clipper Summer '87 version - PUBLIC variables to declare in
your application
Include the following statements and function call in the main
.PRG module of your application (or in your setup procedure if you
use one):
* ----- Declare ClipHelp PUBLIC variables
PUBLIC no_pages,; && (N) ) Used
no_topics,; && (N) ) within
st_rec,; && (N) ) ClipHelp
head_tag,; && (C))
hlp_var,; && (C) Context-sensitivity variable
explode,; && (L) .T. - explode boxes, else .F.
expl_in,; && (N) Box expansion increment 1-2.
expl_dl,; && (N) 0=fastest. Increase to slow.
shadow,; && (L) .T. - shadow boxes, else .F.
mono && (L) .T. - force mono, .F. - color
* ----- Declare default values
STORE 0 TO no_pages, no_topics, st_rec
STORE '' TO hlp_var, head_tag
STORE .T. TO explode && Change these to suit your
STORE .T. TO shadow && preferences. You could use
STORE .F. TO mono && command line parameters in
expl_in = 1 && your application
expl_dl = 5 && if you wish.
* ----- Call function which gathers important information
* from HELP.DAT for later use when <F1> pressed
LdHelpMU()
IMPORTANT: Don't forget to include the all-important LdHelpMU()
function call above in your setup procedure or very early in your
main .PRG file.
12. Clipper 5 version - Declarations in your application
All variables in the Clipper 5 version .OBJ file (CLHLP501.OBJ)
are LOCAL or file-wide STATIC. There is no need to declare any
variables elsewhere in your application.
At the points in your application where you wish to change its
context sensitivity, pass the character string or code with a call
to the function SetHV(). See the section headed 'Clipper 5 -'
under section 9. above for details of its use.
The only line necessary to add to a Clipper 5 application to
provide access to ClipHelp is:
LdHelpMU()
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 14 S.R. Eddy & Assoc
Optionally, the Clipper 5 LdHelpMU() function can have one or more
of the following parameters:
Parameter 1 .T. = force monochrome performance
(default .F.)
Parameter 2 .F. = inhibit panel shadows (default .T.)
Parameter 3 .F. = inhibit panel explosion (default .T.)
Parameter 4 <N> explosion expansion increment 1|2
(default 2)
Parameter 5 <N> explosion expansion delay - the lower the
value the faster the explosion (default 5)
13. Points to remember when using INKEY(0)
If your program uses INKEY(0) and you press <F1> you will not get
on-screen help in the ordinary course because INKEY() is not a
'wait state' like WAIT, ACCEPT, READ, INPUT or MENU TO. To
overcome this, use a function such as:
FUNCTION Await && (C) S.R. Eddy & Associates 1989
* Syntax : Await()
* Purpose : Allow HELP to be accessed during an INKEY(0)
* Dependencies: None
* Returns : INKEY() value
DO WHILE .T.
IF INKEY(0) = 28
* ----- <F1> pressed. Essential to pass dummy
* parameters so that ClipHelp can avoid recursion.
DO HELP WITH "",0,"" && In Clipper 5 you can put Help()
ELSE
EXIT
ENDIF
ENDDO
RETURN ( LASTKEY() )
and replace 'INKEY(0)' with 'Await()' throughout your program.
14. Linking ClipHelp's .OBJ and .LIB files with your application
CLHLPS87.OBJ/CLHLP501.OBJ and HLPCS87.LIB/HLPC501.LIB are all that
are needed to be added to your linker instructions. Proceed as
follows:
Clipper Summer '87:
a) Add 'clhlps87' to the list of object files in your
linker command or .LNK file.
b) Add 'hlpcs87' to the list of libraries in your linker
command or .LNK file.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 15 S.R. Eddy & Assoc
Clipper 5.01
c) Add 'clhlp501' to the list of object files in your
linker command or .LNK file.
d) Add 'hlpc501' to the list of libraries in your linker
command or .LNK file.
IMPORTANT: The library files mentioned above contain functions
written in C. If your application includes overlays please be
sure to refer to the your linker's user manual to see whether it
allows such libraries to be overlaid before attempting to do so.
15. ClipHelp command line parameters
ClipHelp will interpret certain command line parameters given in
the following format:
cliphelp [<topic1>=<on>/<off> [<topic2>=<on>/<off> [...]]]
Parameter options:
a) If ClipHelp thinks you have a color monitor but in fact
you don't, force mono with:
mono=on (default is off)
b) If you find assembly of ClipHelp's opening screen
irritating you can turn it off with:
frag=off (default is on)
c) Turn off box shadows with:
shadow=off (default is on)
d) Turn off exploding boxes with:
explode=off (default is on)
e) Adjust exploding speed by some value between 1 (fast)
and 20 (slow):
explspeed=10 (default is 5)
f) Adjust exploding box increment value between 1 and 2:
explincr=2 (default is 1)
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 16 S.R. Eddy & Assoc
16. Credits
My thanks to Gary Louth and John Buxton for helpful suggestions
during development and for testing the results.
17. Copyright, Trademark etc
Nantucket(R) and Clipper(R) are registered trademarks of Nantucket
Corporation.
QEdit is a registered trademark of Applied Systems Technologies,
Inc.
Turbo GREP is a registered trademark of Borland International.
-------------------------------------------------------------------
ClipHelp (C) User Manual Page 17 S.R. Eddy & Assoc
